Thank you! Always love a docs enhancement.

Now, I'm not opposed to this per se, but I do wanna take a moment to step back and question whether this is the right path to take regardless:

In principle, it shouldn't be that hard for a caller to perform the action of "poll a future, and if it returns Pending but also notifies its Waker before even returning, then poll it again, and repeat." It seems like the main thing holding this back is a slightly weird lack of any established library for it (see e.g. my own code where I modified the pollster crate to be able to do that, but that's a bad example because that code is also doing other weirder things). We could simply not commit to doing this, and expect our users to do it instead. In contrast to cancel safety, this doesn't substantively what functionality we are providing.

Thoughts @djc @Ralith?